/**
 * \file msem182.h
 *
 * Purpose: 	Convenience functions for Semaphores
 *
 * Motivation:	The semop function is hard to use and provides
 *              functionality which is seldom used or even annoying
 *		(like the fact that 0 isn't a nop). These functions
 *		should provide a cleaner interface.
 *
 * Modification history:
 *	2.1	Changed the semantics of mP and mV. The arguments now
 *		specify the index of the semaphore to operate on, 
 *		not the operation.
 *	1.1	got the version from the solution to Ex. 2.11 
 *		(which was derived from an out-of-date version of 
 *		sem182.c which had been heavily hacked by gusti) and
 *		adapted it to the STBS and the newest version of
 *		sem182.c.
 *
 * SCCSId:	"@(#)	msem182.h	2.3	6/27/94	hp"
 * \version $Revision: 1.2 $
 * URL: $HeadURL$
 * Last Modified: $Author: bernd $
 */

#ifndef I_msem182_h
#define I_msem182_h

#include <sys/types.h>


/**
 * Create and initialize a semaphore field.
 * The SF must not exist yet.
 *
 * \param   key     Key of semaphore field
 * \param   nsems   Number of semaphores the field shall contain
 * \param   perm    permission bits for ugo
 * \param   ...     nsems initial values for semaphores
 * \return  The created descriptor an error indicator.
 * \retval  sem-desc if successful
 * \retval  -1      in case of error.
 */
extern int mseminit(const key_t key, const int perm, const int nsems, ...);


/**
 * grab existing semaphore field
 * 
 * \param   key     Key of SF.
 * \param   nsems   number of semaphores in the SF
 * \return  the sem-id or an error indicator
 * \retval  semid   if successful
 * \retval  -1      in case of error
 */
extern int msemgrab (const key_t key, const int nsems);


/**
 * remove semaphore field
 *
 * \param   semid   id of SF to remove
 * \return  the sem-id or an error indicator
 * \retval  semid   if successful
 * \retval  -1      in case of error
 */
extern int msemrm(const int semid);


/**
 * Dijkstra's V for a whole semaphore field.
 *
 * \param   semid   Id of semaphore field
 * \param   nsems   Number of semaphores in the field.
 *			(I am not sure if I should check this. 
 *			It may help catch some errors, but too many
 *			are caught by the OS, and a smaller number 
 *			might be handy if you want only a work on a
 *			subset).
 * \param   ...	     nsems values indicating the semaphores on which
 *			a V operation should be performed.
 * \return  success or error
 * \retval  -1       in case of error
 * \retval  0        otherwise
 */
extern int mV(const int semid, const int nsems, ...);



/**
 * Dijkstra's P for a whole semaphore field.
 * 
 * \param   semid   Id of SF
 * \param   nsems   Number of Semaphores in the field.
 *			(I am not sure if I should check this. 
 *			It may help catch some errors, but too many
 *			are caught by the OS, and a smaller number 
 *			might be handy if you want only a work on a
 *			subset).
 * \param   ...	    nsems values indicating the semaphores on which
 *			a P operation should be performed.
 * \return success or error
 * \retval  -1      in case of error
 * \retval  0       otherwise
 */
extern int mP(const int semid, const int nsems, ...);

#endif /* I_msem182_h */

/*
 * Local Variables:
 * mode: c
 * c-indent-tabs-mode: nil
 * c-basic-offset: 4
 * End:
 */
